From d29a9bba8e64df19a2b396994d14a5e1c88905e6 Mon Sep 17 00:00:00 2001
From: Ben Nicholson <ben@apointless.space>
Date: Mon, 15 Jun 2026 09:56:48 +1000
Subject: [PATCH] Upload files to "PTPLogger"

---
 PTPLogger/README.md | 172 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 172 insertions(+)
 create mode 100644 PTPLogger/README.md

diff --git a/PTPLogger/README.md b/PTPLogger/README.md
new file mode 100644
index 0000000..6ec221f
--- /dev/null
+++ b/PTPLogger/README.md
@@ -0,0 +1,172 @@
+# PTP Monitoring Toolkit
+
+## Overview
+
+This toolkit provides two main components:
+
+- PTP log collector (bash script)
+- PTP graphing tool (Python GUI)
+
+These tools allow you to collect PTP statistics from ptp4l and visualise timing behaviour, including RMS offset, frequency deviation, state changes, and master changes.
+
+---
+
+## 1. PTP Log Collector
+
+### Purpose
+
+The log collector records PTP statistics at approximately 1 Hz and formats them similarly to ptp4l output.
+
+### Example Output
+
+```
+Jun 12 16:49:58 host ptp4l@media1: [6443.95] rms 62 max 191 freq -307 +/- 86 delay 1121 +/- 13
+```
+
+### Running the Collector
+
+Ensure ptp4l is running and accessible via a UNIX socket.
+
+Run the script:
+
+```
+bash PTPLogger.sh
+```
+
+### Requirements
+
+- linuxptp installed
+- pmc available
+- Access to correct ptp4l socket (e.g. /var/run/ptp4l_media1)
+
+### Common Issues
+
+- All values are zero: ptp4l is not synced or no master is present
+- No output: incorrect socket or domain
+
+---
+
+## 2. PTP Graphing Tool
+
+### Purpose
+
+The Python GUI tool visualises collected logs and detects PTP events.
+
+### Features
+
+- Plots RMS offset and frequency deviation
+- Displays PTP state changes
+- Displays master clock changes
+- Adjustable time resolution
+- Handles multi-day logs
+
+### How to Run
+
+```
+python PTPLogger_Graphing.py
+```
+
+### Usage
+
+1. Click "Open Log"
+2. Select a log file
+3. Choose time detail if required
+4. View graphs and event list
+
+### Supported Log Format
+
+The tool requires log lines containing:
+
+```
+rms <value> ... freq <value>
+```
+
+### Graph Interpretation
+
+- RMS: timing accuracy
+- Frequency deviation: servo behaviour
+- Blue vertical lines: state changes
+- Red vertical lines: master changes
+
+---
+
+## 3. Dependencies
+
+### Python Requirements
+
+- Python 3.8 or newer
+
+### Install Dependencies
+
+On both Windows and Linux:
+
+```
+python -m pip install matplotlib
+```
+
+Tkinter is included with most Python installations.
+
+---
+
+## 4. Compilation (Windows)
+
+### Install PyInstaller
+
+```
+python -m pip install pyinstaller
+```
+
+### Build Executable
+
+```
+pyinstaller --onefile --windowed PTPLogger_Graphing.py
+```
+
+### Output
+
+```
+dist/PTPLogger_Graphing.exe
+```
+
+---
+
+## 5. Compilation (Linux)
+
+### Install Dependencies
+
+```
+sudo apt install python3 python3-pip python3-tk
+pip3 install matplotlib pyinstaller
+```
+
+### Build Executable
+
+```
+pyinstaller --onefile --windowed PTPLogger_Graphing.py
+```
+
+### Output
+
+```
+dist/PTPLogger_Graphing
+```
+
+Run:
+
+```
+./dist/PTPLogger_Graphing
+```
+
+---
+
+## 6. Notes
+
+- The graphing tool works best with continuous ptp4l statistics output
+- If logs contain no RMS data, the graph will be empty
+- Correct socket configuration is required for pmc to collect data
+
+---
+
+## Summary
+
+The log collector gathers PTP timing data, and the graphing tool provides visual analysis for troubleshooting and performance monitoring.