14. Time Synchronization
Odin1 Lite supports high-precision time synchronization based on PTP (Precision Time Protocol, IEEE 1588), which can synchronize the device system clock with the host clock to within milliseconds, keeping the hardware timestamps of LiDAR, camera, IMU and other sensor data on the same time base as the host clock. This meets application scenarios with high time-consistency requirements such as multi-sensor fusion and multi-machine collaboration.
Odin1 Lite uses the system clock (SysTick) as the sensor data timestamp source by default. No configuration is required when PTP is not deployed.
14.1 PTP Protocol Principles
14.1.1 Protocol Overview
PTP (IEEE 1588) is a high-precision clock synchronization protocol for local area networks. Compared with NTP (millisecond to tens-of-millisecond level), PTP improves synchronization precision to the sub-microsecond level through hardware timestamping, and is widely used in industrial automation, telecommunications, automotive and robotics fields.
PTP adopts a Master-Slave architecture:
- Master clock (Grandmaster / GM): The time source in the network, usually the host PC or a dedicated clock server;
- Slave clock: A device synchronized to the master clock; Odin1 Lite acts as a slave clock in the synchronization network;
- Boundary Clock (BC) / Transparent Clock (TC): Intermediate network devices (such as PTP switches) that correct link delay hop by hop to avoid cumulative errors introduced by multi-level forwarding.
14.1.2 Synchronization Mechanism (Delay Request/Response Mechanism)
The master and slave clocks complete clock offset and link delay measurement through four types of messages:
Master Clock Slave Clock
│ │
│ ── Sync (t1 hardware timestamp) ────▶ │ t2
│ ── Follow_Up (carries t1) ──────────▶ │
│ │
│ ◀──────────── Delay_Req (t3 stamp)── │ t3
│ ◀──────── Delay_Resp (carries t4)─── │ t4
│ │
Offset: offset = [(t2-t1) - (t4-t3)] / 2
Path delay: delay = [(t2-t1) + (t4-t3)] / 2
- The master clock periodically broadcasts
Syncmessages and stamps the exact time when the message passes through the NIC by PHY/MAC hardware (t1); the slave clock records the reception timestamp (t2). - The
Follow_Upmessage delivers t1 to the slave clock. - The slave clock sends
Delay_Req(stamped t3), and the master clock repliesDelay_Resp(carrying the reception timestamp t4). - The slave clock solves for clock offset and link delay according to the above formulas, and gradually disciplines the local clock.
The key precision guarantee is that t1–t4 are all generated by hardware, eliminating the uncertain delay (jitter up to tens of microseconds) caused by protocol-stack software processing. This is the core advantage of PTP over software NTP solutions.
14.1.3 Transport Protocol: L2 (IEEE 802.3)
PTP messages can be carried over UDP/IPv4 (L3) or directly over Ethernet frames (L2, EtherType 0x88F7). Odin1 Lite uses L2 (IEEE 802.3) transport:
- L2 messages do not pass through the IP protocol stack, resulting in smaller delay and stronger path determinism;
- All PTP ports in the network must be configured to the same transport protocol (in this solution the switch port protocol must be set to IEEE 802.3).
14.1.4 Master-Slave Election (BMCA)
Clocks in the network automatically elect the master clock through the Best Master Clock Algorithm (BMCA) based on clock class, clock accuracy, priority (Priority1/Priority2) and other parameters. In a typical Odin1 Lite deployment, the host PC is explicitly configured as masterOnly, and the switch acts as a boundary clock to synchronize upstream (to Host) and provide a time source downstream (to devices).
14.2 System Architecture
The Odin1 Lite PTP synchronization system consists of three layers:
┌──────────────────┐
│ Host (Master) │ ptp4l(masterOnly) + phc2sys (system clock → NIC PHC)
└────────┬─────────┘
│ IEEE 802.3 (L2 PTP messages)
┌────────┴─────────┐
│ PTP Switch (BC) │ HiSync PTP Switch R01, P0 = management, PTP1~PTP4 = one master three slaves
└────────┬─────────┘
│
┌────────┴─────────┐
│ Odin1 Lite (Slave) │ ptp4l + phc2sys (NIC PHC → system clock) + odin_ptp_daemon
└──────────────────┘
| Component | Role | Description |
|---|---|---|
Host ptp4l | Master clock port | -H (hardware timestamp) -2 (L2 transport) --masterOnly=1 |
Host phc2sys | Clock discipline | Synchronize Host system clock (CLOCK_REALTIME) to NIC PHC |
| PTP switch | Boundary clock (BC) | Upstream follows Host; downstream provides time for up to three devices; SYNC indicator visualizes sync status |
Device ptp4l / phc2sys | Slave clock | Align NIC PHC with master clock and synchronize PHC to device system clock |
Device odin_ptp_daemon | Resident daemon | Manage device-side PTP session, cooperate with driver time-sync mode |
14.3 Network and Switch Configuration
Odin1 Lite builds the synchronization network through the HiSync PTP Switch (model R01, Beijing Feiling Technology):
| Item | Description |
|---|---|
| Port definition | P0: connect to management PC (WebUI configuration, does not participate in PTP); PTP1 ~ PTP4: one master three slave PTP ports |
| WebUI address | http://192.168.1.82 (must be in the same subnet as Odin1 Lite / Host) |
| Login credentials | Username admin / Password admin |
| Indicator | SYNC: green slow flash = PHC not synchronized; green steady = synchronized with upstream PHC |
Configuration steps:
- Connect the management PC to
P0, configure it to the192.168.1.xsubnet, open a browser and visithttp://192.168.1.82to log in to WebUI. - In the left menu, enter “Time Synchronization → PTP” and click “Port Configuration”.
- If the
Protocolcolumn of each PTP port is not L2, click “Edit”, change Protocol to IEEE 802.3 (keep other settings default), and save. - After changing the protocol of all PTP ports to L2, click “Save and Apply” and wait for the switch to restart.
Both the master clock Host and slave devices must be connected to
PTP1 ~ PTP4, notP0.
14.4 Host Configuration
Prerequisite: Confirm that the Host NIC supports hardware timestamping (ethtool -T <nic> output contains hardware-raw-clock / SOF_TIMESTAMPING_RAW_HARDWARE), and confirm the NIC name connected to the switch (the example below uses enp1s0f0; replace with the actual NIC).
# Start ptp4l: L2 transport + hardware timestamp + master-only mode
sudo ptp4l -i enp1s0f0 -m -H -2 --masterOnly=1
# Start phc2sys: synchronize system clock to NIC PHC (in another terminal)
sudo phc2sys -s CLOCK_REALTIME -c enp1s0f0 -m -O 0 -S 0.001
After the Host starts, the switch should first complete synchronization with the Host regardless of whether slave devices are connected — this can be confirmed by the switch SYNC indicator (green steady) or the WebUI “Sync Status” page (sync status, PTP clock time, offset, grandmaster clock info, etc.).
14.5 Hardware Support Check and Software Sync Scheme
14.5.1 How to Determine Whether the Host NIC Supports PTP Hardware Timestamping
PTP hardware timestamping depends on the NIC’s PHC (PTP Hardware Clock). Perform the following checks on the Host:
① Check NIC timestamping capability
ethtool --json -T enp1s0f0 # or older version: ethtool -T enp1s0f0
| Output Keyword | Meaning | Conclusion |
|---|---|---|
hardware-raw-clock: true / SOF_TIMESTAMPING_RAW_HARDWARE and ptp-hardware-clock points to /dev/ptpN | NIC has independent PHC | ✅ Supports hardware sync; deploy as in 14.4 |
Only software-raw-clock: true / SOF_TIMESTAMPING_SOFTWARE | NIC has no PHC | ❌ Does not support hardware sync; switch to 14.5.2 software sync |
Common NICs supporting hardware timestamping: Intel i210/i211/i225/i226, 82574, 82599/X520, X550 series; most consumer onboard NICs (such as Realtek RTL8111/8125, some Intel 1225-V series) do not support it.
② Confirm PHC device node
ls /dev/ptp*
# NICs supporting hardware timestamping will enumerate /dev/ptp0 etc.;
# use the ptp-hardware-clock field in ethtool --json -T enp1s0f0 output to confirm the mapping
③ Verify PHC readability
sudo phc_ctl /dev/ptp0 get
If the current PHC time is returned, the hardware clock is working normally.
The device side (Odin1 Lite) has a built-in PHC hardware clock; the above checks are only for the Host. If the Host does not support hardware sync, the entire link will degrade to software sync precision.
14.5.2 Software Timestamping Scheme (NIC Without PHC)
If the Host NIC does not support hardware timestamping, you can still use linuxptp’s software timestamping mode to complete PTP synchronization: the message stamping point retreats from PHY/MAC to the kernel protocol stack, eliminating user-space processing delay but not kernel send/receive path jitter. Typical synchronization precision degrades from the sub-microsecond level to the hundreds-of-microseconds level (about 10 μs ~ 1 ms).
Only one change is needed on the Host side (compared with 14.4): change ptp4l’s -H (hardware timestamp) to -S (software timestamp):
# Host: software timestamp master clock (-S = software timestamping)
sudo ptp4l -i enp1s0f0 -m -S -2 --masterOnly=1
# phc2sys is no longer applicable (Host has no PHC):
# In -S mode ptp4l timestamps directly from the system clock CLOCK_REALTIME,
# so the Host system clock itself is the published time reference; no additional discipline is needed
# Device side: keep hardware timestamp slave mode unchanged (odin_ptp_daemon / ptp4l -H); no changes required
Note: The device-side PHC is always available; it is recommended to keep hardware timestamp slave mode. The overall link precision bottleneck is on the Host software timestamp side. If the customer has high precision requirements and the Host has no PHC, you can also recommend replacing it with a NIC that supports hardware timestamping (such as Intel i226, low cost and plug-and-play on mainstream distributions).
Precision Expectation and Selection Suggestion
Scheme Host Hardware Requirement Typical Sync Precision Applicable Scenario Hardware PTP (recommended) NIC with PHC Sub-microsecond Multi-sensor tight coupling fusion, motion reconstruction Software PTP (-S) Common NIC 10 μs ~ 1 ms Coarse time alignment, log time synchronization
14.5.3 Alternative Tools Under Software Sync
Software sync has no hardware requirements for the Host NIC, and the implementation tool is not limited to linuxptp. In addition to the default linuxptp (ptp4l), mainstream alternatives are:
| Tool | Protocol/Profile | Platform | Features | Applicability |
|---|---|---|---|---|
| linuxptp (ptp4l + phc2sys) | IEEE 1588-2019 full configuration (including L2/UDP, 802.1AS) | Linux | Official kernel supporting implementation, most complete, supports both soft and hard timestamping | ✅ Recommended, default scheme in this document |
| ptpd2 (PTPd) | IEEE 1588-2008 | Linux/BSD | Old implementation, simple configuration, declining community activity | ⚠️ Usable, no new features, not recommended for new projects |
| OpenAvnu gPTP | IEEE 802.1AS (gPTP) | Linux/Windows | Intel-led, for AVB/TSN audio/video scenarios, usable on Windows | ⚠️ Only recommended for gPTP/TSN scenarios |
Notes:
- 802.1AS (gPTP) note: If the customer environment is an automotive/AVB/TSN network using the gPTP profile, confirm that the PTP switch also supports 802.1AS, and whether the Odin1 Lite daemon is compatible with the corresponding profile; please contact Liuxing technical support for confirmation first.
- ptpd2 and ptp4l cannot run at the same time on the same host; ports will conflict.
- Regardless of the tool chosen, the software sync precision upper limit is determined by the stamping point location (kernel protocol stack), not the tool itself; in the same software timestamp mode, the precision of each tool is basically equivalent.
14.6 Device-side Configuration
The device-side PTP session is automatically managed by the firmware’s built-in odin_ptp_daemon daemon (supporting ptp4l / phc2sys), without any manual operation required by the user.
All user operations are completed on the Host side through ROS services:
The driver provides time-sync mode services (see 5. Data Output):
# Query current sync mode (0=SysTick system clock, 1=PTP)
ros2 service call /manifold/device0/get_sync_mode \
odin_ros_driver_rev1/srv/GetSyncMode "{}"
# Switch to PTP hardware timestamp mode (requires device restart to take effect)
ros2 service call /manifold/device0/set_sync_mode \
odin_ros_driver_rev1/srv/SetSyncMode "{sync_mode: 1}"
After PTP takes effect, sync quality can be queried in real time:
ros2 service call /manifold/device0/get_ptp_sync_status \
odin_ros_driver_rev1/srv/GetPtpSyncStatus "{}"
The returned snapshot contains sync status, clock offset (offset from master), path delay (mean path delay) and frequency adjustment amount, which can be used to quantitatively evaluate synchronization precision.
If
get_ptp_sync_statusshows not synchronized for a long time, please troubleshoot in order: whether the switch port protocol is L2 (14.3) → whether the Host master clock is running (14.4) → whether the device time-sync mode is PTP (14.6); if it still cannot be resolved, please contact Liuxing technical support.
14.7 Sync Verification
- Switch sync status:
SYNCindicator green steady, WebUI “Sync Status” shows synchronized and offset within milliseconds; - PTP sync status query: confirm device-side sync status and offset through
get_ptp_sync_status(see 14.6); - Data timestamp verification: After the Host runs the driver, check that sensor topic timestamps have switched to the synchronized clock:
ros2 launch odin_ros_driver_rev1 odin1Lite.launch.py
ros2 topic echo /manifold/device0/imu --field header.stamp
14.8 Notes
- All network PTP ports must uniformly use the L2 (IEEE 802.3) protocol; mixing UDPv4 will cause sync failure. In software sync mode messages still go through L2, and the switch port configuration requirements remain unchanged.
- After modifying
set_sync_mode, the device must be restarted for it to take effect. - The device-side
odin_ptp_daemonis mutually exclusive with the system defaultptp4l/phc2sys; running them simultaneously will cause sync anomalies. - The Host NIC preferably supports hardware timestamping; if not, it can fall back to software timestamping (
ptp4l -S), but sync precision will degrade significantly (see 14.5). - The PTP switch, Host and device must be in the same subnet; the Host connects to the switch
PTP1 ~ PTP4, and the management PC connects toP0. - It is recommended to periodically monitor the offset through
get_ptp_sync_status; when the offset continues to increase, prioritize checking the link, switch port configuration and Host master clock status.