jan/rusty-telemetry
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: update README.md and project plan for session management and analysis

Browse source
This commit is contained in:
Jan-Peter von Hunnius 2026-06-05 10:48:07 +02:00
parent 47a0896134
commit dc10627842
1 changed files with 63 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

69
README.md
View file

@ -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/<uuid>/
@ -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)