From dc106278428319fe83759f0a13eba40f3101f91c Mon Sep 17 00:00:00 2001 From: "Jan-Peter v. Hunnius" Date: Fri, 5 Jun 2026 10:48:07 +0200 Subject: [PATCH] docs: update README.md and project plan for session management and analysis --- README.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 63 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3a54935..078d9c2 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # rusty-telemetry -Multi-port UDP telemetry listener for sim racing games, with a terminal UI. +Multi-port UDP telemetry listener and analysis platform for sim racing games. -Receives real-time telemetry from **Assetto Corsa** and **Project CARS 1 & 2** via UDP, parses binary packet formats, and displays live data in a terminal dashboard built with ratatui. +Receives real-time telemetry from **Assetto Corsa** and **Project CARS 1 & 2** via UDP, parses binary packet formats, and provides live data via a terminal dashboard and REST API. Supports use-case driven analysis sessions for shift point optimization and track mapping. ## Supported Games @@ -33,6 +33,7 @@ Press **q** or **Ctrl+C** to quit. | `RUSTY_TELEMETRY_LISTEN` | Local address to bind for incoming UDP feeds (Telemetry Tool, PCARS) | `0.0.0.0` | | `RUSTY_TELEMETRY_BIND` | Fallback for both of the above (backward compatibility) | — | | `RUSTY_TELEMETRY_API_PORT` | REST API server port | `8080` | +| `RUSTY_TELEMETRY_API_HOST` | REST API server bind address | `127.0.0.1` | ### Same Machine @@ -129,7 +130,7 @@ Each panel shows: ## Data Capture -A recording is auto-started on launch. All raw UDP packets are written to per-feed JSONL files under a UUID-based directory: +All feeds are continuously recorded into in-memory ring buffers (5 minutes, 18,000 frames per feed). A recording is auto-started on launch; on shutdown, ring buffer contents are flushed to per-feed JSONL files: ``` ./data// @@ -139,7 +140,18 @@ A recording is auto-started on launch. All raw UDP packets are written to per-fe └── feed_5606_pcars.jsonl ``` -Each recording contains a `manifest.json` with metadata (game, track, car, use case, status, timestamps) and JSONL files for each feed. Each line in a JSONL file is a serialized `TelemetryFrame` object, enabling sequential replay and analysis of captured sessions. +Each recording has a `manifest.json` with metadata (game, track, car, use case, status, timestamps) and JSONL files for each feed. Each line is a serialized `TelemetryFrame` object. + +### Session-Based Analysis + +Use-case sessions allow targeted data capture and analysis: + +1. **Create a session** with a use case (`shift_points` or `track_map`) +2. **Start runs** — each run captures frames from the ring buffer between start and stop +3. **Complete the session** — auto-analyzes captured data and stores results +4. **Retrieve analysis** — shift point RPM ranges or track boundary coordinates + +Sessions are in-memory and independent of persistent recordings. ## REST API @@ -159,6 +171,15 @@ A built-in HTTP API server runs on port 8080 for recording management and live t | GET | `/api/recordings/{id}/data/{feed_name}` | Download raw feed JSONL | | GET | `/api/use-cases` | List valid use cases | | GET | `/api/games` | List supported games | +| GET | `/api/sessions` | List all sessions | +| POST | `/api/sessions` | Create analysis session | +| GET | `/api/sessions/{id}` | Get session details | +| DELETE | `/api/sessions/{id}` | Delete session | +| POST | `/api/sessions/{id}/runs` | Start a run | +| POST | `/api/sessions/{id}/runs/{run_id}/stop` | Stop a run | +| POST | `/api/sessions/{id}/complete` | Complete session + auto-analyze | +| GET | `/api/sessions/{id}/analysis` | Get analysis results | +| POST | `/api/sessions/{id}/analyze` | Re-run analysis on completed session | ### Start Recording Body @@ -200,6 +221,40 @@ All fields are optional. } ``` +### Create Session Body + +```json +{ + "use_case": "shift_points", + "label": "Shift Point Analysis Run 1" +} +``` + +### Start Run Body + +```json +{ + "feed_name": "ksudp", + "label": "Acceleration runs" +} +``` + +### Shift Point Analysis Response + +```json +{ + "gear_ranges": [ + { "gear": 2, "gear_display": "1", "min_rpm": 3200, "max_rpm": 8500, "avg_rpm": 6100, "sample_count": 1200 }, + { "gear": 3, "gear_display": "2", "min_rpm": 5800, "max_rpm": 8400, "avg_rpm": 7200, "sample_count": 900 } + ], + "shift_events": [ + { "from_gear": 2, "to_gear": 3, "rpm_before_shift": 8400, "rpm_after_shift": 6100, "rpm_drop": 2300, "speed_kmh": 95.0 } + ], + "recommended_shift_rpm": 8400.0, + "total_frames_analyzed": 2100 +} +``` + ## Testing ```bash @@ -217,9 +272,11 @@ cargo test ``` src/ ├── main.rs Multi-port UDP listener, TUI event loop, KSUDP handshake -├── api.rs REST API server (axum) for recording management and live telemetry +├── api.rs REST API server (axum) — recordings, sessions, live telemetry +├── recording.rs Recording manager — ring buffers, manifest CRUD, flush to JSONL +├── session.rs Session manager — use-case sessions, runs, frame extraction +├── analysis.rs Analysis algorithms — shift points, track mapping ├── binary_utils.rs Shared safe binary read helpers (bounds-checked, zero fallback) -├── recording.rs Recording session manager (manifest, CRUD, auto-start) ├── telemetry_frame.rs Unified telemetry data model (TelemetryFrame) ├── feed_state.rs Per-feed health/frequency state machine with ring buffer ├── parser_ksudp.rs AC KSUDP binary parser (RTCarInfo, 6 tests)