docs: add integrators' guide, PTP architecture tips

.markdownlint.yml

@@ -9,5 +9,4 @@ MD024:
   siblings_only: true
 MD033: false
 MD041: false
-MD046:
-  style: fenced
+MD046: false

.vscode/settings.json

@@ -23,7 +23,8 @@
   "yaml.customTags": [
     "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
     "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
-    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+    "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format",
+    "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify"
   ],
   "yaml.schemas": {
     "diag_master/schema/config.schema.json": "diag_master/config/*.yml"

README.md

@@ -13,6 +13,7 @@ The tools currently handle monitoring
 - local and remote PTP instances by implementing a PTP Management Client
 
 Documentation is available at [**sync-tooling.pages.dev**](https://sync-tooling.pages.dev/) :book:
+(log in with your `@tier4.jp` email address).
 
 ## Ansible (Recommended)
 

docs/css/mermaid-tweaks.css

@@ -1,4 +1,9 @@
 .mermaid {
   display: flex;
   justify-content: center;
+}
+
+.center-contents {
+  display: flex;
+  justify-content: center;
 }

docs/index.md

@@ -10,7 +10,12 @@ Takes the **pain** out of **p**recision time synchroniz**a**t**i**o**n**.
 * :simple-ros: plug-and-play compatible with ROS 2 `/diagnostics`
 * :octicons-browser-16: confirm system state live in the browser
 
-Set up SYNC.TOOLING for your system: [Getting Started](getting-started.md).
+## :fontawesome-solid-signs-post: First Steps
+
+* [PTP Architecture Guide](ptp-architecture-guide.md) - Set up PTP in a distributed system
+* [Integrators' Guide](integrators-guide.md) - Set up SYNC.TOOLING for a Pilot.Auto based system
+* [Installation Guide](installation.md) - Install SYNC.TOOLING manually
+* [Usage Guide](usage.md) - Configure SYNC.TOOLING for your system
 
 ## :material-tools: SYNC.SETUP
 

docs/getting-started.md → docs/installation.md

@@ -5,11 +5,15 @@ software components necessary:
 - `diag-worker` which runs on every machine running LinuxPTP and provides updates to
    `diag-master`
 
+!!! tip
+    If you are an integrator, or using Pilot.Auto, please refer to the
+    [Integrators Guide](integrators-guide.md) for automated setup instructions.
+
 ## System Requirements
 
 - Ubuntu 22.04
 - ROS 2 Humble with Python3.10 (the default version on Ubuntu 22.04)
-- All machines are in the same IP subnet and can communicate via ROS 2 pub/sub
+- All machines can communicate via ROS 2 pub/sub
 - `pip` must be available
 
 ## Installation

docs/integrators-guide.md

@@ -1,7 +1,69 @@
-This manual is for teams that want to integrate SYNC.DIAG as a part of their vehicle architecture.
+This manual is for teams that want to integrate SYNC.DIAG into their vehicle architecture.
 
-While this page covers the general process of integrating SYNC.DIAG, there are also specific
-guides for integrating with certain vehicle platforms.
+It is assumed that the vehicle is using [Pilot Auto][pilot-auto], is set up using Ansible,
+and has access to [Autoware ECU System Setup][autoware-ecu-system-setup] Ansible roles.
 
-!!! warning
-    This page is under construction.
+[pilot-auto]: https://github.com/tier4/pilot-auto
+[autoware-ecu-system-setup]: https://github.com/tier4/autoware_ecu_system_setup
+
+
+## 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](ptp-architecture-guide.md) 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`.
+
+Please check the configuration example in [this PR](https://github.com/tier4/aip_launcher/pull/529)
+
+## 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 via the [autoware_ecu_system_setup.sync_tooling][role-sync-tooling]
+role on every ECU that participates in PTP synchronization.
+
+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.
+
+!!! bug
+    Again, make sure that, if there are multiple `ptp4l` instances, they have different
+    UDS addresses set via `--uds_address`. Otherwise, SYNC.TOOLING will not be able to
+    communicate with them.
+
+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](installation.md).
+
+More information on the required configuration file can be found in the [Usage Guide](usage.md).
+
+[role-sync-tooling]: https://github.com/tier4/autoware_ecu_system_setup/tree/590fabea4f21811a0a69e26793e4fff4f9b60bd1/roles/sync_tooling
+
+### 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.