Events¶

Ein Event sagt: am Platz ist gerade etwas passiert. Eine Session startet, der Countdown läuft, ein Pilot fliegt durchs Ziel, ein Ergebnis wird bestätigt, ein Pilot wird angelegt. Jedes Event geht gleichzeitig

• an alle Programme am WebSocket /api/v1/ws,
• über die Server-Verbindung (falls eingerichtet; ohne Verbindung bis zu 5 min gepuffert),
• an die Hooks, die auf dieses Event (oder *) eingestellt sind.

Events sind Mitteilungen, keine Befehle: man kann nichts darauf antworten. Wer reagieren will (z. B. ein Rennen bestätigen), schickt einen Befehl.

Aufbau¶

{"type": "event", "event": "pilot_pass", "seq": 17, "time_us": 1792697215501133, "data": {…}}

time_us ist der Zeitpunkt der Meldung, nicht unbedingt des Geschehens: Ein Durchflug wird erst gemeldet, wenn die Erkennung sicher ist (etwa 1 s, nachdem die Drohne das Gate verlassen hat). Die Zeit des Durchflugs selbst steht in data.time_us, und mit der rechnen die Runden.

Sitz¶

Viele Events betreffen einen Piloten auf einem Kanal. Diese Felder heißen hier kurz Sitz und stehen direkt in data:

Ablauf eines Rennens¶

So sieht ein Rennen über 2 Runden mit Holeshot-Start, 3 s Countdown und zwei Piloten aus (vereinfacht):

Darauf kann man sich verlassen:

• session_started kommt vor allem anderen der Session, start_signal vor dem ersten pilot_pass nach dem Start.
• Der pilot_pass, der einen Piloten ins Ziel bringt (finished: true), kommt vor seinem pilot_finished, und alle pilot_finished vor dem session_stopped mit reason: "finished".
• Ein beendetes Rennen wartet auf race_confirmed oder session_deleted; vorher startet keine neue Session.

Andere Fälle:

• Training: kein Countdown; start_signal kommt gleich nach session_started. Der erste Durchflug jedes Piloten ist kind: "start", danach Runden. Es endet nur von Hand (session_stopped mit reason: "stopped", needs_confirmation: false); bestätigt wird nichts.
• Von Hand gestoppt: session_stopped mit reason: "stopped"; ein Rennen braucht danach trotzdem Bestätigung.
• Abgebrochen (Seite: „Abbrechen“, API session.cancel): session_stopped mit reason: "cancelled", gleich danach session_deleted.
• Verworfen (beendetes Rennen nicht bestätigt): session_deleted.

Korrekturen¶

Ein pilot_pass ist eine Live-Meldung. Er kann später noch falsch werden:

• Die Erkennung nimmt nach dem 3. Durchflug eines Kanals frühe Fehltreffer zurück.
• Die Rennleitung löscht, verschiebt oder ergänzt Durchflüge im Editor, auch nach dem Rennen.
• Ein Programm ruft passes.add, passes.delete oder passes.restore.

Dann kommt passes_changed mit der session_id, ohne Einzelheiten: Runden, Plätze und Bestzeiten können sich danach alle verschoben haben. Wer ein Ergebnis anzeigt, holt die Session neu (sessions.get). Deshalb:

• Für Live-Anzeigen (Overlay, Ansage) pilot_pass nehmen.
• Für das, was zählt (Tabelle, Website, Rangliste), das Ergebnis aus race_confirmed, oder nach passes_changed neu holen. session_stopped hat auch ein Ergebnis, aber vor der Durchsicht der Rennleitung.

Durchflüge, die die Freigabe-Regel ablehnt (Zwei Gates), erscheinen gar nicht als pilot_pass; sie sind als gelöscht gespeichert. Durchflüge am Freigabe-Gate selbst sind keine Events.

Alle Events¶

Sessions¶

• start_mode: holeshot (Zeit läuft ab dem ersten Durchflug), from_start (ab dem Startsignal), flying (fliegender Start: der erste Durchflug startet die erste Runde).
• reason: stopped (von Hand), finished (alle im Ziel), cancelled (wird gleich gelöscht).
• needs_confirmation: true bei einem Rennen, das nicht abgebrochen wurde.
• winner: Name des Ersten (wie pilot), null im Training oder ohne Runde.
• results: ein Eintrag pro Sitz, wie in Datenformate → Session.

Durchflüge¶

pilot_pass im Detail:

Beispiel:

{"type": "event", "event": "pilot_pass", "seq": 23, "time_us": 1792697174751210, "data": {
  "session_id": 1, "race": true, "pass_id": 6, "time_us": 1792697173739494, "manual": false,
  "channel": 1, "channel_name": "R3", "mhz": 5732, "pilot_id": 2, "pilot": "ACE",
  "kind": "lap", "lap": 2, "lap_time_us": 13712000, "lap_time_s": 13.712, "laps": 2,
  "best_lap_us": 13104106, "best_lap_s": 13.104, "personal_best": false, "session_best": false,
  "holeshot_us": 2303763, "finished": false, "position": 1}}

total_us in pilot_finished: Zeit vom Startsignal bis zum Zieldurchflug (beim Holeshot also mit dem Weg bis zum ersten Durchflug); beim fliegenden Start null.

Kanäle und Piloten¶

Testen¶

Auf der Seite API & Hooks → Testen läuft ein Log aller Events mit. Ohne Boards geht es auch: Session starten und Durchflüge mit passes.add eintragen; die zählen wie erkannte (manual: true).