# PTP synchronization

PTP synchronization distributes time over Ethernet so supported devices can share a common clock without a dedicated trigger wire.
It is useful when direct FSYNC wiring is impractical, but the deployment still needs clock-aligned capture scheduling.

### Principles and theory

PTP synchronizes device clocks over Ethernet instead of distributing a dedicated electrical trigger. On supported RVC4 platforms,
that shared clock is then used to drive a common frame schedule across devices rather than only to timestamp frames after capture.

In practice what that sync looks like is that epoch time line is divided it into slots, based on the chosen FPS. So in pseudocode

```text
frame_period = 1 / target_fps
slot_index = ptp_time_since_epoch / frame_period
```

Each participating device computes the same `slot_index` from the same PTP-synchronized clock, so they all aim for the same N-th
capture slot.

A PID regulator in the camera stack then nudges the sensor rate slightly above or below the requested FPS until the sensor locks
to that slot schedule. For example, a 30 FPS stream may temporarily run a little faster or slower to remove phase error, then
continue tracking the shared cadence. After that, the [Sync
node](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/sync.md) still pairs the nearest frames together, but
it is working on frames whose capture timing was already driven from the same network-synchronized timeline.

### When to use it

Use PTP synchronization when:

 * devices communicate over Ethernet and cannot share a convenient FSYNC wire
 * cable runs or switch-based topologies make direct daisy-chaining impractical
 * the deployment needs clock-aligned capture scheduling across more than one device

### Support and constraints

PTP scales better than direct FSYNC wiring, but it is less accurate than a shared hardware trigger because timing is distributed
through the network path. It also depends on network equipment that correctly handles PTP traffic.

#### RVC2

### RVC2 implementation

RVC2 does not use Ethernet-based PTP for this synchronization workflow. When an RVC2 deployment needs aligned exposure starts, use
[hardware synchronization (FSYNC)](https://docs.luxonis.com/hardware/platform/deploy/data-sync/hardware-sync.md); when software
grouping is sufficient, use [time based
synchronization](https://docs.luxonis.com/hardware/platform/deploy/data-sync/time-based-sync.md).

#### RVC4

### RVC4 implementation

RVC4 supports PTP-based device time synchronization on supported Ethernet deployments. Configure one device as the PTP master,
keep the others as slaves, and then enable `TIME_PTP` frame sync in the application so sensors use the shared clock as their
timing source and converge onto the same frame slots. By default, this aligns end of exposure; if your workflow needs
start-of-exposure alignment instead, that sync point can be changed.

> **Current sensor support**
> PTP frame was tested on `OG05`, `IMX586`, `OV9282` sensors from the latest batch. If PTP does not work in your setup, contact Luxonis support.

> **PTP network equipment**
> PTP sync only works when the network switch supports PTP traffic. We have tested the following switches and confirmed that they work with OAK4 PTP sync:

 * TP-Link TL-SG1005P
 * Ubiquiti Flex 2.5G PoE (4-port variant)
 * TP-Link TL-SG1008P

In our testing, the 8-port Ubiquiti variant did not work because it blocked PTP traffic. Other switches may also work if they
explicitly support PTP packet handling, but those models are typically more expensive and harder to configure. We recommend using
one of the validated switches above.

### Observed sync accuracy

In our OAK4-CS test setup, we observed the following sync deltas:

| Setup | Mean sync delta | p99 sync delta |
| --- | --- | --- |
| 2x OAK4-CS | 10 us | 100 us |
| 3x OAK4-CS | <15 us | >100 us |

These numbers are indicative rather than guaranteed. Actual sync accuracy depends on switch behavior, topology, and network load.

### Setting it up

On the master device:

```bash
luxonis-ptp-config enable
luxonis-ptp-config mode master
```

On slave devices:

```bash
luxonis-ptp-config enable
luxonis-ptp-config mode slave
```

If camera configuration has been overridden from the default, also run this on every participating device:

```bash
luxonis-ptp-config sync_frames true
```

In application code, enable:

```python
cam.initialControl.setFrameSyncMode(dai.CameraControl.FrameSyncMode.TIME_PTP)
```

This tells the camera to use the PTP-synchronized device clock as the source for frame timing. The camera stack then continuously
adjusts the actual sensor cadence around the requested FPS so each device stays locked to the same slot on the shared timeline.
The [Sync node](https://docs.luxonis.com/software-v3/depthai/depthai-components/nodes/sync.md) can then group the nearest matching
frames from those already aligned captures.

PTP sync and external FSYNC use the same `depthai-core` examples. For PTP, run them with the `--ptp-sync` flag:

 * [Python multi-device frame sync
   example](https://github.com/luxonis/depthai-core/blob/main/examples/python/Misc/MultiDevice/multi_device_frame_sync.py)
 * [C++ multi-device frame sync
   example](https://github.com/luxonis/depthai-core/blob/main/examples/cpp/Misc/MultiDevice/multi_device_frame_sync.cpp)