Added intial plugin

This commit is contained in:
2026-05-19 15:38:16 +10:00
commit 47178f0415
21 changed files with 5701 additions and 0 deletions

440
public/openapi.json Normal file
View File

@@ -0,0 +1,440 @@
{
"openapi": "3.1.0",
"info": {
"title": "Project CARS UDP Telemetry API",
"version": "1.0.0",
"description": "Local API for decoded Project CARS UDP telemetry. The game sends binary UDP packets; this app decodes them into JSON, serves current state snapshots, exposes a server-sent events stream, and calculates a race overview leaderboard."
},
"servers": [
{
"url": "http://localhost:3000",
"description": "Default local development server"
}
],
"tags": [
{
"name": "State",
"description": "Decoded packet state snapshots"
},
{
"name": "Leaderboard",
"description": "Server-calculated race overview"
},
{
"name": "Events",
"description": "Live telemetry stream. The current server implementation uses Server-Sent Events at /events; it does not expose a WebSocket upgrade endpoint."
},
{
"name": "Ingest",
"description": "Telemetry frame ingestion"
},
{
"name": "Pages",
"description": "Static browser pages served by the local app"
},
{
"name": "Schemas",
"description": "Reusable JSON schemas"
}
],
"x-websocket-routes": [],
"x-streaming-routes": [
{
"protocol": "sse",
"path": "/events",
"events": ["state", "packet", "leaderboard"]
}
],
"paths": {
"/": {
"get": {
"tags": ["Pages"],
"summary": "Open packet viewer page",
"description": "Serves the main packet inspection UI from public/index.html.",
"operationId": "getPacketViewerPage",
"responses": {
"200": {
"description": "HTML packet viewer page",
"content": {
"text/html": {
"schema": { "type": "string" }
}
}
}
}
}
},
"/overview.html": {
"get": {
"tags": ["Pages"],
"summary": "Open race overview page",
"description": "Serves the leaderboard/race overview UI.",
"operationId": "getOverviewPage",
"responses": {
"200": {
"description": "HTML race overview page",
"content": {
"text/html": {
"schema": { "type": "string" }
}
}
}
}
}
},
"/swagger.html": {
"get": {
"tags": ["Pages"],
"summary": "Open Swagger documentation page",
"description": "Serves the browser documentation UI for this OpenAPI document.",
"operationId": "getSwaggerPage",
"responses": {
"200": {
"description": "HTML Swagger page",
"content": {
"text/html": {
"schema": { "type": "string" }
}
}
}
}
}
},
"/api/state": {
"get": {
"tags": ["State"],
"summary": "Get latest decoded UDP packet state",
"description": "Returns the latest merged packet by UDP packet type plus the most recent parsed packets, newest first.",
"operationId": "getState",
"responses": {
"200": {
"description": "Current decoded packet state",
"content": {
"application/json": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json"
}
}
}
}
}
}
},
"/api/leaderboard": {
"get": {
"tags": ["Leaderboard"],
"summary": "Get calculated leaderboard overview",
"description": "Returns participant rows merged from UDP packets, including timing, status, nationality override, car name, lap splits, sector splits, pit state, and decoded race flag data.",
"operationId": "getLeaderboard",
"responses": {
"200": {
"description": "Current leaderboard overview",
"content": {
"application/json": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json#/$defs/leaderboard"
}
}
}
}
}
}
},
"/api/ingest/shared-memory": {
"post": {
"tags": ["Ingest"],
"summary": "Ingest shared-memory bridge packets",
"description": "Receives packet-like JSON frames from scripts/shared_memory_bridge.py and merges them into the same state used by the UDP parser and leaderboard.",
"operationId": "ingestSharedMemory",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json#/$defs/sharedMemoryIngestRequest"
}
}
}
},
"responses": {
"200": {
"description": "Frame accepted",
"content": {
"application/json": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json#/$defs/ingestAccepted"
}
}
}
},
"400": {
"description": "Invalid frame",
"content": {
"application/json": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json#/$defs/errorResponse"
}
}
}
}
}
}
},
"/events": {
"get": {
"tags": ["Events"],
"summary": "Open live telemetry SSE stream",
"description": "Server-Sent Events stream. This is the app's live route; there is no WebSocket upgrade route in the current server. On connection it sends a `state` event. For each parsed UDP packet it sends a `packet` event containing the packet, state and leaderboard, followed by a `leaderboard` event containing just the leaderboard.",
"operationId": "streamEvents",
"x-streaming-protocol": "sse",
"x-sse-events": {
"state": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json#/$defs/stateEvent"
},
"example": {
"latest": {
"3": {
"receivedAt": "2026-05-18T06:31:12.812Z",
"source": "192.168.1.55:5606",
"base": {
"packetNumber": 1210,
"categoryPacketNumber": 309,
"partialPacketIndex": 0,
"partialPacketNumber": 1,
"packetType": 3,
"packetVersion": 1
},
"name": "Timings",
"size": 1064,
"data": {
"numParticipants": 2,
"eventTimeRemaining": 1275.442,
"participants": [
{
"slot": 0,
"racePosition": 1,
"active": true,
"currentLap": 5,
"currentTime": 402.733,
"mpParticipantIndex": 1001
}
]
}
}
},
"recent": [],
"leaderboard": {
"rows": [
{
"id": 1001,
"slot": 0,
"position": 1,
"status": {
"code": "racing",
"label": "Racing",
"tone": "good"
},
"driver": "Alex Taylor",
"lap": 5,
"currentTime": 402.733
}
],
"note": "1 participant merged from UDP packets",
"session": {
"trackName": "Bathurst - Mount Panorama",
"sessionType": "Race",
"timeLeft": 1275.442,
"weather": "22 C air / 31 C track / rain 0",
"lastUpdate": "2026-05-18T06:31:12.812Z"
}
}
}
},
"packet": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json#/$defs/packetEvent"
},
"example": {
"packet": {
"receivedAt": "2026-05-18T06:31:13.020Z",
"source": "192.168.1.55:5606",
"base": {
"packetNumber": 1211,
"categoryPacketNumber": 310,
"partialPacketIndex": 0,
"partialPacketNumber": 1,
"packetType": 3,
"packetVersion": 1
},
"name": "Timings",
"size": 1064,
"data": {
"numParticipants": 2,
"eventTimeRemaining": 1274.991,
"participants": [
{
"slot": 0,
"racePosition": 1,
"active": true,
"sector": 2,
"currentLap": 5,
"currentTime": 403.184,
"currentSectorTime": 32.333,
"mpParticipantIndex": 1001
}
]
}
},
"state": {
"latest": {},
"recent": []
},
"leaderboard": {
"rows": [],
"note": "Waiting for participant or timing packets",
"session": {
"trackName": "-",
"sessionType": "-",
"weather": "-"
}
}
}
},
"leaderboard": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json#/$defs/leaderboard"
},
"example": {
"rows": [
{
"id": 1001,
"slot": 0,
"sortPosition": 1,
"position": 1,
"active": true,
"status": {
"code": "racing",
"label": "Racing",
"tone": "good"
},
"driver": "Alex Taylor",
"nationality": {
"code": "GBR",
"country": "United Kingdom",
"source": "udp"
},
"vehicle": "Formula A",
"lap": 5,
"sector": 2,
"currentTime": 403.184,
"lastLapTime": 83.214,
"fastestLapTime": 82.901
}
],
"note": "1 participant merged from UDP packets",
"session": {
"trackName": "Bathurst - Mount Panorama",
"sessionType": "Race",
"timeLeft": 1274.991,
"weather": "22 C air / 31 C track / rain 0",
"lastUpdate": "2026-05-18T06:31:13.020Z"
}
}
}
},
"responses": {
"200": {
"description": "SSE stream of telemetry updates",
"content": {
"text/event-stream": {
"schema": {
"type": "string",
"description": "Server-Sent Events stream. Event names currently include `state`, `packet`, and `leaderboard`; payload schemas are documented in `x-sse-events`."
},
"examples": {
"state": {
"summary": "State event after timing and participant packets",
"value": "event: state\ndata: {\"latest\":{\"2\":{\"receivedAt\":\"2026-05-18T06:31:12.420Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1201,\"categoryPacketNumber\":42,\"partialPacketIndex\":1,\"partialPacketNumber\":2,\"packetType\":2,\"packetVersion\":1},\"name\":\"Participants\",\"size\":1136,\"data\":{\"participantsChangedTimestamp\":88342,\"participants\":[{\"slot\":0,\"localSlot\":0,\"partialPacketIndex\":1,\"name\":\"Alex Taylor\",\"nationality\":85,\"index\":1001},{\"slot\":1,\"localSlot\":1,\"partialPacketIndex\":1,\"name\":\"Sam Rivera\",\"nationality\":226,\"index\":1002}]}},\"3\":{\"receivedAt\":\"2026-05-18T06:31:12.812Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1210,\"categoryPacketNumber\":309,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"participantsChangedTimestamp\":88342,\"eventTimeRemaining\":1275.442,\"splitTimeAhead\":0,\"splitTimeBehind\":1.248,\"splitTime\":1.248,\"localParticipantIndex\":0,\"participants\":[{\"slot\":0,\"worldPosition\":[124,0,842],\"orientation\":[0,1024,0],\"currentLapDistance\":2840,\"racePosition\":1,\"active\":true,\"sector\":2,\"sectorRaw\":2,\"sectorExtraPrecision\":0,\"highestFlag\":0,\"pitModeSchedule\":0,\"carIndex\":45,\"raceState\":2,\"currentLap\":5,\"currentTime\":402.733,\"currentSectorTime\":31.882,\"mpParticipantIndex\":1001},{\"slot\":1,\"worldPosition\":[118,0,806],\"orientation\":[0,1008,0],\"currentLapDistance\":2790,\"racePosition\":2,\"active\":true,\"sector\":2,\"sectorRaw\":2,\"sectorExtraPrecision\":0,\"highestFlag\":2,\"pitModeSchedule\":0,\"carIndex\":47,\"raceState\":2,\"currentLap\":5,\"currentTime\":403.981,\"currentSectorTime\":33.130,\"mpParticipantIndex\":1002}]}}},\"recent\":[{\"receivedAt\":\"2026-05-18T06:31:12.812Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1210,\"categoryPacketNumber\":309,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"eventTimeRemaining\":1275.442,\"participants\":[]}}],\"leaderboard\":{\"rows\":[{\"id\":1001,\"slot\":0,\"sortPosition\":1,\"position\":1,\"active\":true,\"status\":{\"code\":\"racing\",\"label\":\"Racing\",\"tone\":\"good\"},\"driver\":\"Alex Taylor\",\"nationality\":{\"code\":\"GBR\",\"country\":\"United Kingdom\",\"source\":\"udp\"},\"vehicle\":\"Formula A\",\"vehicleShortName\":\"FORM\",\"lap\":5,\"sector\":2,\"currentTime\":402.733,\"currentSectorTime\":31.882,\"lastLapTime\":83.214,\"fastestLapTime\":82.901,\"pitModeSchedule\":0,\"highestFlag\":0,\"raceState\":2,\"raceStateCode\":2,\"invalidatedLap\":false,\"carIndex\":45},{\"id\":1002,\"slot\":1,\"sortPosition\":2,\"position\":2,\"active\":true,\"status\":{\"code\":\"blue_flag\",\"label\":\"Blue flag\",\"tone\":\"warn\"},\"driver\":\"Sam Rivera\",\"nationality\":{\"code\":\"USA\",\"country\":\"United States\",\"source\":\"udp\"},\"vehicle\":\"Formula A\",\"vehicleShortName\":\"FORM\",\"lap\":5,\"sector\":2,\"currentTime\":403.981,\"currentSectorTime\":33.13,\"lastLapTime\":84.012,\"fastestLapTime\":83.441,\"pitModeSchedule\":0,\"highestFlag\":2,\"flag\":{\"raw\":2,\"colour\":2,\"reason\":0,\"observed\":\"blue\"},\"raceState\":2,\"raceStateCode\":2,\"invalidatedLap\":false,\"carIndex\":47}],\"note\":\"2 participants merged from UDP packets\",\"session\":{\"trackName\":\"Bathurst - Mount Panorama\",\"sessionType\":\"Race\",\"timeLeft\":1275.442,\"weather\":\"22 C air / 31 C track / rain 0\",\"lastUpdate\":\"2026-05-18T06:31:12.812Z\"}}}\n\n"
},
"packet": {
"summary": "Packet event with state and leaderboard",
"value": "event: packet\ndata: {\"packet\":{\"receivedAt\":\"2026-05-18T06:31:13.020Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1211,\"categoryPacketNumber\":310,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"participantsChangedTimestamp\":88342,\"eventTimeRemaining\":1274.991,\"splitTimeAhead\":0,\"splitTimeBehind\":1.192,\"splitTime\":1.192,\"localParticipantIndex\":0,\"participants\":[{\"slot\":0,\"worldPosition\":[128,0,851],\"orientation\":[0,1026,0],\"currentLapDistance\":2875,\"racePosition\":1,\"active\":true,\"sector\":2,\"sectorRaw\":2,\"sectorExtraPrecision\":0,\"highestFlag\":0,\"pitModeSchedule\":0,\"carIndex\":45,\"raceState\":2,\"currentLap\":5,\"currentTime\":403.184,\"currentSectorTime\":32.333,\"mpParticipantIndex\":1001}] }},\"state\":{\"latest\":{\"3\":{\"receivedAt\":\"2026-05-18T06:31:13.020Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1211,\"categoryPacketNumber\":310,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"eventTimeRemaining\":1274.991,\"participants\":[]}}},\"recent\":[{\"receivedAt\":\"2026-05-18T06:31:13.020Z\",\"source\":\"192.168.1.55:5606\",\"base\":{\"packetNumber\":1211,\"categoryPacketNumber\":310,\"partialPacketIndex\":0,\"partialPacketNumber\":1,\"packetType\":3,\"packetVersion\":1},\"name\":\"Timings\",\"size\":1064,\"data\":{\"numParticipants\":2,\"eventTimeRemaining\":1274.991,\"participants\":[]}}]},\"leaderboard\":{\"rows\":[{\"id\":1001,\"slot\":0,\"sortPosition\":1,\"position\":1,\"active\":true,\"status\":{\"code\":\"racing\",\"label\":\"Racing\",\"tone\":\"good\"},\"driver\":\"Alex Taylor\",\"lap\":5,\"sector\":2,\"currentTime\":403.184,\"currentSectorTime\":32.333}],\"note\":\"1 participant merged from UDP packets\",\"session\":{\"trackName\":\"Bathurst - Mount Panorama\",\"sessionType\":\"Race\",\"timeLeft\":1274.991,\"weather\":\"22 C air / 31 C track / rain 0\",\"lastUpdate\":\"2026-05-18T06:31:13.020Z\"}}}\n\n"
},
"leaderboard": {
"summary": "Leaderboard update event",
"value": "event: leaderboard\ndata: {\"rows\":[{\"id\":1001,\"slot\":0,\"sortPosition\":1,\"position\":1,\"active\":true,\"status\":{\"code\":\"racing\",\"label\":\"Racing\",\"tone\":\"good\"},\"driver\":\"Alex Taylor\",\"nationality\":{\"code\":\"GBR\",\"country\":\"United Kingdom\",\"source\":\"udp\"},\"vehicle\":\"Formula A\",\"vehicleShortName\":\"FORM\",\"lap\":5,\"sector\":2,\"currentTime\":403.184,\"currentSectorTime\":32.333,\"checkpointSplit\":{\"source\":\"checkpoint\",\"basis\":\"raceOrder\",\"checkpoint\":\"L5 S2\",\"time\":403.184,\"delta\":0},\"lastLapTime\":83.214,\"latestLapSplit\":null,\"fastestLapTime\":82.901,\"bestLapSplit\":null,\"fastestSectors\":[27.101,28.334,27.466],\"pitModeSchedule\":0,\"pit\":{\"raw\":0,\"pitMode\":0,\"pitSchedule\":0},\"highestFlag\":0,\"flag\":{\"raw\":0,\"colour\":0,\"reason\":0},\"raceState\":2,\"raceStateCode\":2,\"invalidatedLap\":false,\"carIndex\":45},{\"id\":1002,\"slot\":1,\"sortPosition\":2,\"position\":2,\"active\":true,\"status\":{\"code\":\"blue_flag\",\"label\":\"Blue flag\",\"tone\":\"warn\"},\"driver\":\"Sam Rivera\",\"nationality\":{\"code\":\"USA\",\"country\":\"United States\",\"source\":\"udp\"},\"vehicle\":\"Formula A\",\"vehicleShortName\":\"FORM\",\"lap\":5,\"sector\":2,\"currentTime\":404.376,\"currentSectorTime\":33.525,\"checkpointSplit\":{\"source\":\"checkpoint\",\"basis\":\"raceOrder\",\"checkpoint\":\"L5 S2\",\"comparedTo\":\"P1\",\"time\":404.376,\"delta\":1.192},\"lastLapTime\":84.012,\"latestLapSplit\":{\"comparedTo\":\"P1\",\"time\":84.012,\"referenceTime\":83.214,\"delta\":0.798},\"fastestLapTime\":83.441,\"bestLapSplit\":{\"comparedTo\":\"P1\",\"time\":83.441,\"referenceTime\":82.901,\"delta\":0.54},\"fastestSectors\":[27.488,28.619,27.334],\"pitModeSchedule\":0,\"pit\":{\"raw\":0,\"pitMode\":0,\"pitSchedule\":0},\"highestFlag\":2,\"flag\":{\"raw\":2,\"colour\":2,\"reason\":0,\"observed\":\"blue\"},\"raceState\":2,\"raceStateCode\":2,\"invalidatedLap\":false,\"carIndex\":47}],\"note\":\"2 participants merged from UDP packets\",\"session\":{\"trackName\":\"Bathurst - Mount Panorama\",\"sessionType\":\"Race\",\"timeLeft\":1274.991,\"weather\":\"22 C air / 31 C track / rain 0\",\"lastUpdate\":\"2026-05-18T06:31:13.020Z\"}}\n\n"
}
}
}
}
}
}
}
},
"/openapi.json": {
"get": {
"tags": ["Schemas"],
"summary": "Get this OpenAPI document from the static public route",
"operationId": "getOpenApiSpec",
"responses": {
"200": {
"description": "OpenAPI 3.1 document",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/api/openapi.json": {
"get": {
"tags": ["Schemas"],
"summary": "Get this OpenAPI document from the API alias",
"description": "Serves the same public/openapi.json document as /openapi.json.",
"operationId": "getOpenApiSpecApiAlias",
"responses": {
"200": {
"description": "OpenAPI 3.1 document",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/schemas/udp-packets.schema.json": {
"get": {
"tags": ["Schemas"],
"summary": "Get decoded UDP packet JSON Schema",
"description": "JSON Schema used by the OpenAPI document for decoded packet state and leaderboard responses.",
"operationId": "getUdpPacketSchema",
"responses": {
"200": {
"description": "JSON Schema for decoded UDP packets",
"content": {
"application/schema+json": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json"
}
},
"application/json": {
"schema": {
"$ref": "/schemas/udp-packets.schema.json"
}
}
}
}
}
}
}
}
}