Integrators' Guide
This manual is for teams that want to integrate SYNC.DIAG into their vehicle architecture.
It is assumed that the vehicle is set up using Ansible. This repository provides Ansible roles
for PTP and SYNC.TOOLING configuration in the ansible/
directory.
Pre-Requisites
Setup ECU IP Configuration and PTP
The ECU, sensor and network architecture has been decided and set up. This includes things like Netplan configuration and IP address assignments.
The network architecture has to be compatible with the specific ECUs' and sensors' supported PTP profiles.
The PTP Architecture Guide has been followed to set up the PTP architecture, including all PTP4L and PHC2SYS configuration.
Setup Diagnostics in Sensor Driver
Setup nebula>=v0.2.8 and sensor configuration to output synchronization meta data on /sync_diag/graph_updates.
For other sensor drivers
For more information on how to integrate external sensor drivers, see the Sensor Driver Integration Guide.
Please check the configuration example in this PR
SYNC.DIAG
Once a PTP architecture is set up, SYNC.DIAG can be configured to monitor synchronization status and publish it to ROS 2.
Setup
Install and configure SYNC.DIAG using the Ansible roles provided in this repository:
diag_worker- Run on every ECU with PTPdiag_master- Run once per vehicle
The SYNC.DIAG Master is only required once, and should be run on an ECU that publishes or
processes ROS 2 /diagnostics. Usually, the main Autoware ECU is a good choice.
SYNC.DIAG Workers are required on every ECU that participates in PTP synchronization, including
the one running the SYNC.DIAG Master. Each worker has to be configured with a list of
ptp4l and phc2sys instances to monitor.
Named Unix Domain Sockets
When using the ptp4l Ansible role from this repository, each instance automatically gets
a unique Unix domain socket at /var/run/ptp4l@<name>. This is required for SYNC.TOOLING
to communicate with ptp4l instances.
All ECUs running a SYNC.DIAG Worker and/or Master must be able to communicate over ROS 2, as
the /sync_diag/graph_updates topic is used to send status updates to the master.
More information on requirements can be found in the Manual Installation Guide.
More information on the required configuration file can be found in the Usage Guide.
Example Playbook
# Minimal Two-ECU Synchronization Example
#
# This playbook demonstrates a complete PTP synchronization setup:
#
# main_ecu (Grandmaster):
# - System clock (UTC) is the time source
# - phc2sys syncs CLOCK_REALTIME -> eth0 PHC (PTP Hardware Clock), converting
# UTC to TAI
# - PTPv2 server (hardware timestamping) on eth0 (for automotive sensors)
# - Runs diag-master to aggregate diagnostics
# - Runs diag-worker to monitor local clocks
#
# sensing_ecu (Sensor Host):
# - PTPv2 client (software timestamping) on eno1 (syncs from main_ecu)
# - phc2sys syncs CLOCK_REALTIME -> eno2 PHC, staying in UTC
# - gPTP (hardware timestamping) server on eno2 for connected sensors
# - Runs diag-worker to monitor local clocks
---
# =============================================================================
# MAIN ECU - Grandmaster
# =============================================================================
- hosts: main_ecu
roles:
# -------------------------------------------------------------------------
# PTPv2 server (hardware timestamping) on eth0
# -------------------------------------------------------------------------
- role: ptp4l
vars:
ptp4l_instance_name: eth0
ptp4l_interfaces: ["eth0"]
ptp4l_mode: server
ptp4l_config_file: /usr/share/doc/linuxptp/configs/default.cfg
# -------------------------------------------------------------------------
# Sync system clock (UTC) to eth0's PHC, converting to TAI
# -------------------------------------------------------------------------
- role: phc2sys
vars:
phc2sys_instance_name: sys_to_eth0
phc2sys_source: CLOCK_REALTIME
phc2sys_destinations: ["/dev/ptp0"] # eth0's PHC
phc2sys_utc_offset: 37 # Convert UTC -> TAI
# -------------------------------------------------------------------------
# Diagnostic worker - monitors local PTP services
# -------------------------------------------------------------------------
- role: diag_worker
vars:
diag_worker_ros_setup_script: /opt/ros/humble/setup.bash
diag_worker_ptp4l_units:
# A ptp4l role with `name` produces a systemd unit `ptp4l@<name>`
- ptp4l@eth0
diag_worker_phc2sys_units:
# A phc2sys role with `name` produces a systemd unit `phc2sys@<name>`
- phc2sys@sys_to_eth0
# -------------------------------------------------------------------------
# Diagnostic master - aggregates status from all workers
# -------------------------------------------------------------------------
- role: diag_master
vars:
diag_master_ros_setup_script: /opt/ros/humble/setup.bash
diag_master_enable_web_ui: true
diag_master_config:
clock_tree:
# main_ecu.sys is the grandmaster (UTC system clock)
main_ecu.sys:
# eth0's PHC is synced from system clock via phc2sys
main_ecu.ptp0:
# sensing_ecu's system clock syncs from main_ecu via software PTP
# on eno1
sensing_ecu.sys:
# eno2's PHC is synced from system clock via phc2sys
sensing_ecu.ptp1:
# The LiDAR sensor syncs from sensing_ecu.eno2's PHC
sensor@lidar/top:
diagnostics:
diff_thresholds:
ptp_master:
warn: 100
error: 1000
unit: us
phc2sys:
warn: 100
error: 1000
unit: us
measurement:
warn: 1
error: 20
unit: ms
# =============================================================================
# SENSING ECU - Sensor Host
# =============================================================================
- hosts: sensing_ecu
roles:
# -------------------------------------------------------------------------
# Software PTP client on eno1 (syncs from main_ecu)
# Uses software timestamping - the clock is the system clock itself
# -------------------------------------------------------------------------
- role: ptp4l
vars:
# Software PTP client - receives time from main_ecu's gPTP server
ptp4l_instance_name: eno1
ptp4l_interfaces: ["eno1"]
ptp4l_mode: client
# Use default.cfg with software timestamping (-S flag added by linuxptp)
# Note: TAI->UTC conversion happens automatically when using software
# timestamping
ptp4l_config_file: /usr/share/doc/linuxptp/configs/default.cfg
# -------------------------------------------------------------------------
# Hardware gPTP server on eno2 (for connected sensors)
# -------------------------------------------------------------------------
- role: ptp4l
vars:
ptp4l_instance_name: eno2
ptp4l_interfaces: ["eno2"]
ptp4l_mode: server
ptp4l_config_file: /usr/share/doc/linuxptp/configs/gPTP.cfg
# -------------------------------------------------------------------------
# Sync system clock to eno2's PHC, staying in UTC (no offset conversion)
# The system clock is already in UTC (synced via software PTP on eno1)
# -------------------------------------------------------------------------
- role: phc2sys
vars:
phc2sys_instance_name: sys_to_eno2
phc2sys_source: CLOCK_REALTIME
phc2sys_destinations: ["/dev/ptp1"] # eno2's PHC
phc2sys_utc_offset: 0 # Stay in UTC - no TAI conversion
# -------------------------------------------------------------------------
# Diagnostic worker - monitors local PTP services
# -------------------------------------------------------------------------
- role: diag_worker
vars:
diag_worker_ros_setup_script: /opt/ros/humble/setup.bash
diag_worker_ptp4l_units:
- ptp4l@eno1
- ptp4l@eno2
diag_worker_phc2sys_units:
- phc2sys@sys_to_eno2
Running SYNC.DIAG
SYNC.DIAG is started automatically as a systemd service on every ECU that has been configured.
To make sure it is working correctly, check the output in ROS 2 /diagnostics. Also check
that none of the services crash or fail to start.
Running SYNC.DOCTOR
To access the web interface SYNC.DOCTOR, the SYNC.DIAG Master has to be launched with the
--web-ui option. This will start a web server on port 5000 of the ECU running the master.