jan/racecraft
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
racecraft/README.md

7.9 KiB
Raw Blame History

Racecraft

Web-based sim racing telemetry analysis client. Connects to rusty-telemetry via its REST API and provides live telemetry visualization, session management, and data analysis.

Architecture

┌─────────────────────────────────────────────────┐
│  Sim Machine                                     │
│                                                  │
│  ┌──────────────┐  ┌───────────────┐            │
│  │ Assetto      │  │ rusty-        │            │
│  │ Corsa        │──│ telemetry     │            │
│  │ (UDP out)    │  │ :8080 (API)   │            │
│  └──────────────┘  └───────────────┘            │
│                    ┌───────────────┐            │
│                    │ racecraft     │            │
│                    │ :5173 (Vite)  │            │
│                    └───────────────┘            │
└─────────────────────────────────────────────────┘
                      │
                 LAN / WiFi
                      │
           ┌──────────────────┐
           │  Other machine   │
           │  Browser         │
           └──────────────────┘
  • rusty-telemetry listens for UDP telemetry from sim games on ports 9996, 10101, 5606
  • racecraft is a Vue.js SPA that talks to the rusty-telemetry REST API via a Vite dev proxy
  • The Vite dev server binds to 0.0.0.0, making it accessible from other machines on the LAN
  • API calls (/api/*) are proxied to http://127.0.0.1:8080

Features

Dashboard

  • System status overview: API server connectivity, sim connection state, active recording
  • Live feed cards with health indicators, frequency, and telemetry snapshot
  • Quick access to live telemetry and session management
  • Recent sessions list

Live Telemetry

  • Real-time gauges: speed (km/h), RPM, gear indicator
  • Throttle and brake input bars
  • Lap time and track position (spline)
  • Per-feed status cards with health, frequency, and packet stats
  • Polling at 250ms for responsive updates

Session Management

  • Create analysis sessions with use case selection (Shift Points, Track Mapping)
  • Start/stop runs within a session to capture telemetry data
  • Complete sessions to trigger automatic analysis
  • Session detail view with run history and status

Shift Point Analysis

  • Gear RPM range visualization (min/avg/max bar chart)
  • Shift event timeline (RPM before/after each upshift)
  • Recommended shift RPM from aggregated data
  • Detailed shift event table

Car Grip Analysis

  • Grip envelope chart: peak lateral/accel/brake G vs speed (envelope extraction)
  • Grip circle scatter: longitudinal G vs lateral G (friction circle)
  • Cornering grip vs speed curve
  • Steering response: steer angle vs lateral G scatter
  • Summary stats: max lateral/accel/brake/combined G

Car Characteristics

  • Aggregated shift-point profiles per car across all sessions
  • Expandable car cards showing per-gear RPM/speed ranges
  • Recommended shift RPM per car

Track Mapping

  • Canvas-rendered track boundaries from coordinate data
  • Center line computation from left/right boundary runs
  • Boundary legend with point counts
  • Persistent track models with track list and detail views
  • Responsive canvas that redraws on window resize

Tech Stack

Layer Technology
Framework Vue 3.5 (Composition API, <script setup>)
Language TypeScript 5.7
Build Vite 6
Routing Vue Router 4
State Pinia 3
HTTP Axios
Charts Chart.js 4 + vue-chartjs 5
Track Map HTML Canvas 2D
Styling CSS with custom properties (dark theme)

Getting Started

Prerequisites

Install

cd ~/WebstormProjects/racecraft
npm install

Run (Development)

Start both the backend and frontend:

# Terminal 1 — Backend (rusty-telemetry)
cd ~/RustroverProjects/rusty-telemetry
RUSTY_TELEMETRY_API_HOST=0.0.0.0 cargo run --release

# Terminal 2 — Frontend (racecraft)
cd ~/WebstormProjects/racecraft
npm run dev

Vite will output:

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://192.168.1.x:5173/
  • From the same machine: open http://localhost:5173
  • From another machine: open http://192.168.1.x:5173 (the Network URL)

The RUSTY_TELEMETRY_API_HOST=0.0.0.0 env var makes the backend API accessible from all network interfaces. In dev mode, the Vite proxy handles routing /api/* to the backend.

Production Build

npm run build

Output is in dist/. Serve with any static file server, or configure axum in rusty-telemetry to serve the built files.

Project Structure

racecraft/
├── index.html
├── package.json
├── vite.config.ts              # host: 0.0.0.0, proxy /api → localhost:8080
├── tsconfig.json
├── src/
│   ├── main.ts                 # App bootstrap (Vue + Pinia + Router)
│   ├── App.vue                 # Root layout with navigation
│   ├── router/index.ts         # 9 routes with lazy loading
│   ├── types/index.ts          # TypeScript interfaces matching API JSON shapes
│   ├── api/client.ts           # Typed Axios client (all API endpoints)
│   ├── stores/
│   │   ├── telemetry.ts        # Live telemetry with polling + derived status
│   │   ├── sessions.ts         # Session CRUD, run management, analysis
│   │   └── tracks.ts           # Track model list + detail
│   ├── views/
│   │   ├── DashboardView.vue   # System status, feeds, quick actions
│   │   ├── LiveView.vue        # Real-time gauges and telemetry
│   │   ├── SessionsView.vue    # Session list with create/delete
│   │   ├── SessionDetailView.vue # Run workflow, complete, analyze
│   │   ├── ShiftPointsView.vue # RPM charts and shift event table
│   │   ├── GripAnalysisView.vue # Grip envelope, grip circle, steering response
│   │   ├── CharacteristicsView.vue # Car characteristics aggregation
│   │   ├── TracksView.vue      # Track model list
│   │   └── TrackDetailView.vue # Canvas track map renderer
│   ├── components/
│   │   └── FeedStatus.vue      # Reusable feed card with health + telemetry
│   └── assets/
│       └── main.css            # Dark theme, CSS variables, utilities
└── public/
    └── favicon.ico

API Contract

Racecraft consumes the rusty-telemetry REST API (28 endpoints). See the rusty-telemetry README for full endpoint documentation.

Key endpoints used:

  • GET /api/live — polled every 250ms–1000ms for live telemetry
  • GET /api/sessions / POST /api/sessions — session management
  • POST /api/sessions/{id}/runs / POST /api/sessions/{id}/runs/{run_id}/stop — run capture
  • POST /api/sessions/{id}/complete — complete session and trigger analysis
  • GET /api/sessions/{id}/analysis — retrieve analysis results
  • GET /api/characteristics/cars — aggregated car shift-point profiles
  • GET /api/characteristics/cars/{car} — detailed per-gear data for a car
  • GET /api/tracks / GET /api/tracks/{game}/{track_name} — track model list and detail
  • POST /api/tracks/build — build track model from completed session

License

Private project — not yet licensed for distribution.