Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions src/core/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,12 @@ add_subdirectory(schema_compat)
# log during its own construction.
add_subdirectory(log_bridge)

# Chrony evidence parsing and capture-time qualification (no dependency on the rest of the product).
# POSIX clocks only, so the Windows source build skips it.
if(NOT WIN32)
add_subdirectory(timesync)
endif()

# Build OXR Utils first - header-only utilities (no dependencies)
add_subdirectory(oxr_utils)

Expand Down
25 changes: 25 additions & 0 deletions src/core/timesync/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

cmake_minimum_required(VERSION 3.20)

# Chrony evidence parsing, wall-to-monotonic conversion and capture qualification. Standard library and POSIX
# clocks only, so it also configures on its own (cmake -S src/core/timesync) and builds without CUDA, LiveKit
# or Python.
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR)
project(isaaccapture_timesync LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)
include(CTest)
endif()

add_subdirectory(cpp)

# Standalone configure runs the module's tests; in the product tree tests/cpp/core adds them.
if(CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR AND BUILD_TESTING)
cmake_path(GET CMAKE_CURRENT_SOURCE_DIR PARENT_PATH _core_dir)
cmake_path(GET _core_dir PARENT_PATH _src_dir)
cmake_path(GET _src_dir PARENT_PATH _repo_dir)
add_subdirectory(${_repo_dir}/tests/cpp/core/timesync tests)
endif()
122 changes: 122 additions & 0 deletions src/core/timesync/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# timesync

Converts a camera host's wall-clock capture time to the PC's monotonic clock and decides whether
the result may be recorded. The PC runs a measuring-only `chronyd` that follows the camera host and never adjusts
the PC's clock, so the two wall clocks keep their offset; the library applies that measured offset (the difference
of the two hosts' `System time`) to each capture time. It reads chrony's own report of how well it is doing and
refuses a frame it cannot vouch for.

Target `timesync::timesync` (consumers include `<timesync/...>`). POSIX only, so the Windows source
build skips it. It builds without CUDA, LiveKit or Python, and on its own:

```bash
cmake -S src/core/timesync -B build -DBUILD_TESTING=ON && cmake --build build && ctest --test-dir build
```

## Integration boundary

This module supplies reusable clock evidence and capture-time qualification. It does not publish anything:
publication is done by the consumer, currently the camera_livekit_bridge `chrony_clock` adapter. The module is
intended to remain the estimator behind the receiver backend's clock mapping. Reported uncertainty describes the
supported measurement model; it is not independent proof of physical timestamp accuracy.

| Current path | Intended owner or replacement | Reuse, adapt or retire | Follow-up and landing condition |
| --- | --- | --- | --- |
| `src/core/timesync/` | The estimator behind the receiver backend's clock mapping | Reuse the chrony evidence handling and qualification; adapt the output to the mapping | Preserve qualified mappings and validity and uncertainty behaviour behind the destination interface. Lands when the receiver backend publishes the mapping. |

## Pieces

| Header | Role |
| --- | --- |
| `chrony_tracking.hpp` | Strict parser for one `chronyc -c tracking` line; `is_synchronised`. |
| `local_clock.hpp` | Bracketed realtime/monotonic sample and a tracker that numbers the intervals between realtime steps. |
| `capture_qualifier.hpp` | `qualify_capture`: PC-monotonic capture time with its summed uncertainty (`usable()`; `Qualified` also met the budget), or a typed refusal. |
| `chrony_monitor.hpp`, `command_runner.hpp` | Background `chronyc` poll: no shell, a timeout, an output cap, never in the frame path. |
| `tools/timesync_tool.py` | Sets up the chrony the library reads (below). Python standard library only. |

## Usage

A consumer keeps a `ChronyMonitor` for the PC and one for the camera host, a `LocalClockTracker`
fed by `sample_local_clock`, and calls `qualify_capture` per frame. The caller pins the clock
generation when a take starts and ends the take if a frame reports another. A `ChronyMonitor` can
query a chronyd over its command port (`host` and `port` in `ChronyMonitorConfig`), which is how a
dedicated unprivileged instance next to the system chronyd is read.

## Arrangement

The camera host keeps its own clock and serves it (it may follow UTC or serve its own clock). A second,
unprivileged chronyd on the PC measures it and never adjusts the PC's system clock, so nothing has to reach the
PC (a PC firewall does not matter) and the PC needs no root beyond installing chrony. `qualify_capture` charges
the PC's full root delay and dispersion, which include the link between the two and the camera host's own upstream
error (see "What the bound assumes").

A camera host with no upstream source is served as synchronised only if its chrony has a `local` reference; pass
`configure-remote --offline` to write one. It is off by default, so a host that follows UTC keeps its configuration.
`status` is a readiness check on the PC's follower (synchronised, the camera host's reference id and root dispersion under
`--max-dispersion-ms`, finite values). The measured offset to the camera host is reported, not limited: the follower
never adjusts the PC's clock, so it stays, and `qualify_capture` applies it to each capture. `status` does not state
the per-frame bound.

## Running and deploying it

`tools/timesync_tool.py` (Python standard library only):

```bash
# On the PC: install chrony if it is missing (needs sudo).
python3 src/core/timesync/tools/timesync_tool.py ensure-local

# Install and start chrony on the camera host, let this PC measure it and read its state
# (needs passwordless sudo and the network there; bounded by --timeout, default 90 s).
python3 src/core/timesync/tools/timesync_tool.py configure-remote user@camera-host --host-lan-ip PC_LAN_IP

# On the PC, in the foreground: measure the camera host's clock.
python3 src/core/timesync/tools/timesync_tool.py follow --server CAMERA_HOST_IP

# Read-only: has this PC settled on the camera host? Exits non-zero with the reasons when not.
python3 src/core/timesync/tools/timesync_tool.py status --remote CAMERA_HOST_IP --wait 120
```

The PC instance copies the system `chronyd` binary into its work directory, because the distribution's AppArmor
profile is tied to `/usr/sbin/chronyd` and would stop it reading a configuration outside `/etc/chrony`. Deploy and
launch tools call this tool; they do not carry their own chrony setup.

## What the bound assumes

`qualify_capture` first moves the sender's wall stamp onto the PC's wall clock by the measured offset, the difference
of the two hosts' `System time` (chrony's NTP clock minus the system clock; in `chronyc -c` output a positive value means
the system clock is slow). The PC's NTP clock is the camera host's, so the offset is the PC's `System time` minus the
camera host's, and a fixed offset of either sign is converted correctly. The inter-host term bounds what is left: the
PC's full root dispersion and root delay / 2, a slack for the camera host's dispersion growing since the PC copied it,
and each report's skew and frequency times its age (how far the correction can have moved since the report).

The camera host's own root values are not subtracted. They would cancel its upstream error only if both hosts' root
fields described the same upstream sample, and chrony's report carries no identifier that shows it: `Ref time` is when
each host processed its own latest measurement, so comparing the two says nothing about which samples the root fields
came from. Subtracting without that correspondence could shrink the bound with no new measurement of the link, so the
PC's full values are charged. They include the camera host's upstream error, so the bound is larger than the link
alone and never smaller; a camera host disciplined from the internet (large root delay) will usually be over the
budget, and those frames keep their capture time.

What is and is not checked: the PC's selected reference id must be the camera host's address, so a different source
is refused as `ReferenceMismatch`. The bound is derived from chrony's own reports. It has not been validated against an
independent reference such as a hardware sync pulse, so a qualified frame means "within chrony's claimed error",
not "measured within". Refusal policy: any report that is stale, has no recent source update, is unsynchronised, or
names another source is refused and the frame carries no time; nothing is estimated. A frame that passes every check
but whose bound is over the budget is `OverBudget`, which is still `usable()`: it keeps its capture time and the
bound, and the budget is a precision target for the diagnostics, not a condition for having a time.

Step detection compares successive wall-minus-monotonic offsets. On Linux the two clocks share
frequency adjustment, so the difference changes only on a step. A change beyond both bracket widths
plus a margin (100 us by default) counts as one; a smaller step goes undetected, so that margin is
added to every conversion's uncertainty. Detection also takes one sample interval.

A report is refused when chronyd was last asked too long ago, and also when its last source update
is older than `max_source_update_age_ns`, so frequent polling cannot hide a quiet reference.

The parser expects the 14-field `chronyc -c tracking` layout of chrony 4.5 and fails closed on any
other field count.
29 changes: 29 additions & 0 deletions src/core/timesync/cpp/CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

cmake_minimum_required(VERSION 3.20)

find_package(Threads REQUIRED)

add_library(timesync STATIC
chrony_tracking.cpp
local_clock.cpp
capture_qualifier.cpp
command_runner.cpp
chrony_monitor.cpp
)

target_include_directories(timesync
INTERFACE
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/inc>
)

target_link_libraries(timesync
PRIVATE
Threads::Threads
)

target_compile_features(timesync PUBLIC cxx_std_17)
target_compile_options(timesync PRIVATE -Wall -Wextra)

add_library(timesync::timesync ALIAS timesync)
Loading
Loading