195 lines
7.9 KiB
Markdown
195 lines
7.9 KiB
Markdown
# Racecraft
|
||
|
||
Web-based sim racing telemetry analysis client. Connects to [rusty-telemetry](https://codeberg.org/jhunnius/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
|
||
|
||
- Node.js 18+ and npm
|
||
- [rusty-telemetry](https://codeberg.org/jhunnius/rusty-telemetry) running on the same machine
|
||
|
||
### Install
|
||
|
||
```bash
|
||
cd ~/WebstormProjects/racecraft
|
||
npm install
|
||
```
|
||
|
||
### Run (Development)
|
||
|
||
Start both the backend and frontend:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
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](https://codeberg.org/jhunnius/rusty-telemetry) 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.
|